Add RegisterTools API to McpClient for pre-populating tool cache by tarekgh · Pull Request #1590 · modelcontextprotocol/csharp-sdk

tarekgh · 2026-05-20T17:42:03Z

Summary

This PR adds AddKnownTools, RemoveKnownTools, and ClearKnownTools APIs to McpClient that allow pre-populating the internal tool cache with tool definitions. This enables MCP clients to send Mcp-Param-* HTTP headers (based on x-mcp-header schema annotations) without requiring a prior ListToolsAsync call.

Fixes #1577

Changes

API Additions on `McpClient`

AddKnownTools(IEnumerable<Tool>) — registers tool definitions in the client's tool cache with all-or-nothing validation
RemoveKnownTools(IEnumerable<string>) — removes specific known tools by name
ClearKnownTools() — removes all known tools

Base virtual methods throw NotSupportedException (not abstract, to preserve API compatibility with PackageValidationBaselineVersion=1.0.0).

Implementation Details

Known tools are added to the same _toolCache used by ListToolsAsync
A thread-safe ConcurrentDictionary<string, byte> tracks known tool names (used as a concurrent set)
ToolCacheClearing (invoked by ListToolsAsync) only removes server-discovered tools; known tools survive cache clears
Fast path: when no known tools exist, _toolCache.Clear() is called directly
All-or-nothing validation: tools are validated for x-mcp-header correctness before any are added; ArgumentException thrown on invalid schemas
Re-registering a tool with the same name overwrites the previous definition (last write wins)
If the server returns a tool with the same name as a known tool, the server's definition overwrites in the cache, but the tool retains its known/pinned status
LogDebug on cache miss during tools/call to help diagnose missing Mcp-Param-* headers

Cache Interaction Behavior

AddKnownTools -> ListToolsAsync: known tools survive the clear, server tools added alongside
ListToolsAsync -> AddKnownTools: both coexist in cache
AddKnownTools -> ListToolsAsync -> AddKnownTools: all known tools survive, server tools refreshed
RemoveKnownTools/ClearKnownTools: removes from both _registeredToolNames and _toolCache

Documentation

Conceptual docs section "Pre-loading tool definitions on the client" in docs/concepts/tools/tools.md
XML docs on all three methods with cache interaction details

Tests

Unit Tests (20 tests in `McpClientAddKnownToolsTests.cs`)

Register then list — server tools repopulated correctly
Multiple ListToolsAsync cycles with registered tools
List then register ordering
Register -> list -> register again
Same name as server tool (server overwrites definition, pinned status preserved)
Invalid x-mcp-header schema rejection (all-or-nothing)
Duplicate registration (last write wins)
Null argument validation (AddKnownTools, RemoveKnownTools)
No-header-annotation tools still accepted
Register then CallToolAsync without ListToolsAsync (cache lookup works)
RemoveKnownTools — removed tool no longer survives ListToolsAsync
RemoveKnownTools — non-existent name is no-op
RemoveKnownTools — partial remove, other tools survive
ClearKnownTools — removes all, server tools unaffected
ClearKnownTools — empty is no-op
ClearKnownTools then AddKnownTools — works correctly
Partial-failure atomicity — [valid, invalid, valid] throws, nothing cached
Null element atomicity — null at index 1 throws, element 0 not cached

HTTP Integration Tests (6 tests in `AddKnownToolsHeaderTests.cs`)

Core scenario: AddKnownTools -> CallToolAsync (NO ListToolsAsync) -> verify Mcp-Param-Region and Mcp-Param-Priority headers received by server
No headers sent without register or list
Known tool headers survive ListToolsAsync cache clear
RemoveKnownTools -> no headers sent after removal
Staleness: register -> server returns [] -> ListToolsAsync -> call -> headers still sent
Last-write-wins: register schema A -> register schema B -> call -> headers reflect schema B only

This enables MCP clients to send Mcp-Param-* HTTP headers without requiring a prior ListToolsAsync call, addressing issue modelcontextprotocol#1577. Changes: - Add RegisterTools abstract method to McpClient with XML documentation - Implement RegisterTools in McpClientImpl with thread-safe ConcurrentDictionary for registered tool name tracking - Modify ToolCacheClearing to preserve registered tools across ListToolsAsync calls while clearing server-discovered tools - Add fast path optimization when no tools are registered - Validate x-mcp-header annotations on registered tools Tests: - 11 unit tests covering cache interaction scenarios - 3 HTTP integration tests verifying Mcp-Param-* headers are sent without ListToolsAsync

Adding an abstract member to McpClient is a breaking change (CP0005) because existing subclasses would fail to compile. Changed to virtual with a default no-op implementation that validates the argument.

tarekgh · 2026-05-20T18:49:07Z

#1553

halter73

Thanks for tackling this! CI checked, and we're ahead of the other tier 1 SDKs here. TypeScript (modelcontextprotocol/typescript-sdk#2069) only landed Mcp-Method/Mcp-Name, Python has no SEP-2243 implementation at all, and Go shipped x-mcp-header (modelcontextprotocol/go-sdk#915) with the same silent-omission gap that #1577 calls out. So this PR is paving the path for everyone.

One thing I'd like to see addressed before merge but couldn't comment on inline because it's out of the diff range: the silent-miss path in McpClientImpl.SendRequestAsync. If the caller forgets to call either RegisterTools or ListToolsAsync, the cache lookup fails, no Tool is attached, and StreamableHttpClientSessionTransport ships the tools/call with no Mcp-Param-* headers — no warning, no log, no error. The server then sees a tools/call with no infra headers and may misroute (e.g. a proxy keyed on Mcp-Param-Region). Worth a LogDebug (or LogInformation, gated on the negotiated protocol version supporting SEP-2243) on the cache miss so it's at least diagnosable. Other SDKs have the same gap, but logging is cheap and a real footgun-mitigator.

Follow-up, not for this PR: I'd also like us to eventually offer a fully stateless way to flow parameter values into Mcp-Param-* headers — e.g. a Tool (or just a param → header map) passed directly on CallToolAsync / CallToolRequestOptions, with no client-wide cache mutation. The cache-priming approach in this PR is the right answer for the "I already know the schema from a previous session" scenario, but for callers who want per-call control (multi-tenant proxies, request-scoped routing, callers who don't want any client-global mutable state) the stateless variant is a cleaner fit and dovetails with what the Python folks are circling in modelcontextprotocol/python-sdk#1509. I'm happy to file a separate issue once this lands.

Clarifies that this is client-side cache priming, not server-side tool registration. Renamed method, test classes, and test files.

…hen-commit - Add RemoveKnownTools(IEnumerable<string>) to remove specific known tools - Add ClearKnownTools() to remove all known tools - Change AddKnownTools to validate all tools first, then commit all-or-nothing - Throw ArgumentException on invalid x-mcp-header annotations instead of silently skipping (ToolRejected still fires for logging parity) - Remove trailing blank line in McpClient.cs - Add 7 unit tests for Remove/Clear scenarios - Add HTTP integration test for RemoveKnownTools header verification

Validate all tool names for null before removing any, matching the all-or-nothing pattern used in AddKnownTools.

Add 'Pre-loading tool definitions on the client' section to docs/concepts/tools/tools.md covering usage, cache behavior, removal APIs, and validation semantics.

Prevents subclasses that don't override from silently swallowing calls. All three methods (AddKnownTools, RemoveKnownTools, ClearKnownTools) now throw with a descriptive message.

Clarify that known status is sticky for the McpClient lifetime and point to RemoveKnownTools/ClearKnownTools for explicit removal.

- Staleness: register → server returns [] → headers still sent - Partial-failure atomicity: [valid, invalid, valid] → nothing cached - Null element atomicity: null at index 1 → nothing cached - Last-write-wins: re-register with schema B → headers reflect B

When SendRequestAsync handles a tools/call request and the tool is not found in the cache, log a Debug message suggesting AddKnownTools or ListToolsAsync to populate the cache. This makes missing Mcp-Param-* headers diagnosable without breaking existing behavior.

tarekgh · 2026-05-21T19:54:14Z

@halter73 thanks for your feedback. I believe I addressed all your feedback. The remaining open discussions looks can be addressed outside this PR. Let me know if you have any more feedback.

…ols-api

Log a Warning (instead of Debug) when a tools/call request has no cached tool definition, but only for StreamableHttpClientSessionTransport where Mcp-Param-* headers are relevant. Pipe/stdio transports do not emit this warning since headers do not apply. Added tests: - Pipe transport: cache miss does NOT log a warning - HTTP transport: cache miss DOES log a warning

tarekgh requested review from halter73 and mikekistler May 20, 2026 17:46

tarekgh self-assigned this May 20, 2026

tarekgh and others added 2 commits May 20, 2026 10:59

Merge branch 'main' into feature/register-tools-api

2a15504

Fix API compat: change RegisterTools from abstract to virtual

dfbfdca

Adding an abstract member to McpClient is a breaking change (CP0005) because existing subclasses would fail to compile. Changed to virtual with a default no-op implementation that validates the argument.

halter73 reviewed May 21, 2026

View reviewed changes

Tarek Mahmoud Sayed added 8 commits May 21, 2026 10:51

Rename RegisterTools to AddKnownTools

7a817b3

Clarifies that this is client-side cache priming, not server-side tool registration. Renamed method, test classes, and test files.

Make RemoveKnownTools validate-then-commit for atomicity

bebef8a

Validate all tool names for null before removing any, matching the all-or-nothing pattern used in AddKnownTools.

Add conceptual docs for AddKnownTools/RemoveKnownTools/ClearKnownTools

d45480b

Add 'Pre-loading tool definitions on the client' section to docs/concepts/tools/tools.md covering usage, cache behavior, removal APIs, and validation semantics.

Base virtual methods throw NotSupportedException instead of no-op

46c65dc

Prevents subclasses that don't override from silently swallowing calls. All three methods (AddKnownTools, RemoveKnownTools, ClearKnownTools) now throw with a descriptive message.

Document sticky registration and escape hatch in AddKnownTools docs

65c33d2

Clarify that known status is sticky for the McpClient lifetime and point to RemoveKnownTools/ClearKnownTools for explicit removal.

Merge remote-tracking branch 'upstream/main' into feature/register-to…

495f48a

…ols-api

halter73 reviewed May 26, 2026

View reviewed changes

Comment thread src/ModelContextProtocol.Core/Client/McpClientImpl.cs Outdated

halter73 approved these changes May 26, 2026

View reviewed changes

tarekgh merged commit 157f855 into modelcontextprotocol:main May 26, 2026
17 of 18 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add RegisterTools API to McpClient for pre-populating tool cache#1590

Add RegisterTools API to McpClient for pre-populating tool cache#1590
tarekgh merged 13 commits into
modelcontextprotocol:mainfrom
tarekgh:feature/register-tools-api

tarekgh commented May 20, 2026 •

edited

Loading

Uh oh!

tarekgh commented May 20, 2026

Uh oh!

halter73 left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tarekgh commented May 21, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

tarekgh commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

API Additions on McpClient

Implementation Details

Cache Interaction Behavior

Documentation

Tests

Unit Tests (20 tests in McpClientAddKnownToolsTests.cs)

HTTP Integration Tests (6 tests in AddKnownToolsHeaderTests.cs)

Uh oh!

tarekgh commented May 20, 2026

Uh oh!

halter73 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tarekgh commented May 21, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

tarekgh commented May 20, 2026 •

edited

Loading

API Additions on `McpClient`

Unit Tests (20 tests in `McpClientAddKnownToolsTests.cs`)

HTTP Integration Tests (6 tests in `AddKnownToolsHeaderTests.cs`)